Mac Format 1996 April/MacFormat CD Edition MF36 (April 1996).iso/Shareware City/Developers/Tools Plus - GUI⁄Event libs/Tools Plus 2.6.1a Evaluat'n Kit/Tools Plus 2.6.1a/User Manual/14-System Polling (3 of 4)

INI File | 1994-12-12 | 31KB | 649 lines

[Display using Monaco 9]


doNothing (event)
`````````````````
No event has occurred.  Also called a “null event.”

  The doNothing event indicates that the event queue is empty and that no event has occurred.  This occurs only when PollSystem returns with a value of false.

Programming Considerations
``````````````````````````
• If your application does “background processing,” that is, it performs
  an on-going process while it is waiting for events, it should perform
  “one cycle” of its background process each time it receives a
  doNothing event.  A single cycle of your application’s background
  process should take no longer than 1/60 of a second.  See the
  SetNullTime routine to set the interval at which your application
  receives doNothing events.

• Picture buttons with the “repeating events” option turned on may
  produce doNothing events if your application calls PollSystem more
  frequently than the button changes its value.  This will cause no ill
  side-effects, but you should be aware of this

------------------------------------------------------------------------

doChgWindow (event)
```````````````````
Request to activate an inactive window that belongs to your application.

  The request to activate an inactive window is made in response to the user clicking anywhere on an inactive window that belongs to your application.  However, there is one exception.  If the user clicks in an inactive window’s title bar while holding the Command key, the window is dragged without being activated.

Programming Considerations
``````````````````````````
• A window can be activated by using the ActivateWindow procedure.

• If the active window has an active editing field, you may want to
  validate the edited text before allowing the user to activate another
  window.  If this is the case, use GetFieldString to obtain a copy of
  the edited text, then your application can check the string for
  errors.  If an error is detected, display an appropriate alert box and
  ignore the doChgWindow event.  If no error is detected, call the
  SaveFieldString procedure to save the edited text as the field’s
  string, then activate the required window.

• If your application decides not to allow the user to activate a
  window, it should display an appropriate alert box to explain why.

• The doChgWindow event will never occur when a modal window is active,
  or when the watch cursor is displayed since other windows belonging to
  your application cannot be clicked.

• A doChgWindow event does not occur if the user clicks on a tool bar or
  floating palettes.

• If your application is running under Finder (System 6 or prior), a
  doChgWindow event will not occur when the user [1] clicks a desk
  accessory from an active window, [2] clicks a desk accessory from
  another active desk accessory, or [3] clicks the previously active
  window from an active desk accessory.  These are all handled
  automatically.

Valid Polling Record Fields
```````````````````````````
Poll.Window

------------------------------------------------------------------------

doRefresh (event)
`````````````````
A window’s contents need to be refreshed (redrawn) after Tools Plus has refreshed its own objects.

  Your application must respond to this event.  The doRefresh event occurs when a window is completely or partially obscured, then becomes uncovered.  Tools Plus takes care of redrawing buttons, scroll bars, editing fields, list boxes, pop-up menus, picture buttons and custom controls.  Your application must take care of refreshing anything else, such as icons, pictures, lines, or text that it may have put in the window.  When your application receives this event, Tools Plus will have already drawn its objects.

  When a doRefresh event is reported, the window’s “update region” defines the exact area that needs to be refreshed, excluding the objects drawn by Tools Plus (buttons, scroll bars, editing fields, list boxes, pop-up menus, picture buttons and custom controls).  Although you can redraw everything in the window, the actual drawing is limited to the parts of the window that are visible and which need refreshing (Tools Plus changes the window’s update region to exclude its own objects).

  Your application can ignore the doRefresh event if you have chosen to do all the necessary drawing in response to a doPreRefresh event, or if the only objects in the window are drawn by Tools Plus (buttons, picture buttons, scroll bars, editing fields, list boxes, pop-up menus, and custom controls).

Programming Considerations
``````````````````````````
• If your application did not put anything in the window except buttons,
  picture buttons, scroll bars, editing fields, list boxes, pop-up
  menus, and custom controls, it can ignore this event.

• If your application responds to a doRefresh event, it should do so in
  the following manner:


CurrentWindow(Poll.Window);            {Make the affected window the   }
                                       {  current grafPort.            }
BeginUpdate(WindowPointer(Poll.Window));{Drawing will occur only within}
                                        {  the area that needs         }
                                        {  refreshing (includes all    }
                                        {  monitors).                  }
for theScreen:=1 to NumberOfScreens do {Repeat drawing for each monitor}
  begin                                {  in which the window appears. }
    BeginUpdateScreen(theScreen);      {Drawing area reduced to the    }
                                       {  specified screen.            }

    {   …insert your color-dependent drawing code here…   }

    EndUpdateScreen;                   {End the drawing for this       }
                                       {  monitor, and restore the     }
                                       {  window’s visible (drawing)   }
  end;                                 {  region.                      }

 {   …insert your color-independent drawing code here…   }

EndUpdate(WindowPointer(Poll.Window)); {End the update for the window  }
CurrentWindowReset;                    {Reset the current window to be }
                                       {  the same as the active window}
                                       {  (optional command).          }


• BeginUpdate temporarily sets the window’s visRgn (visible region where
  drawing occurs) to the intersection of the visRgn and updateRgn
  (region requiring updating).  This effectively restricts drawing to
  the area that needs updating.  Tools Plus removes its own objects
  (buttons, scroll bars, editing fields, list boxes, pop-up menus,
  picture buttons and custom controls) from the updateRgn, so you don’t
  have to worry about accidentally drawing over those objects

• It is possible that several windows will need to be refreshed
  simultaneously if, if for instance, a closing window exposed three
  windows behind it.  PollSystem reports a single doRefresh event each
  time it is called in the event loop, one event for each window that
  needs refreshing.

• Unlike ordinary Macintosh applications, a doRefresh event is not
  generated when a window is first opened.

• A doRefresh event is not generated for desk accessories, the Dialog
  Manager’s dialogs, alerts, or Dynamic Alerts.  These events are
  handled automatically.

• When responding to a doRefresh event, your application should limit
  itself to activities that pertain only to refreshing the specified
  window.  Do not create or modify user interface elements, open, close,
  or move windows.

• See the doPreRefresh event if your application needs to refresh all or
  part of the window before Tools Plus refreshes its own objects
  (buttons, picture buttons, scroll bars, editing fields, list boxes,
  pop-up menus, and custom controls).

Valid Polling Record Fields
```````````````````````````
Poll.Window

------------------------------------------------------------------------

doPreRefresh (event)
````````````````````
A window’s contents may be refreshed (redrawn) before Tools Plus refreshes its own objects.

  Most applications will ignore this event.  A doPreRefresh event is reported before each doRefresh event (which occurs when a window is completely or partially obscured, then becomes uncovered and needs to be redrawn).  The doPreRefresh event lets your application draw or display objects before Tools Plus draws its own objects (buttons, picture buttons, scroll bars, editing fields, list boxes, pop-up menus, and custom controls).

  An example of the doPreRefresh event’s usefulness is if your application displays a picture as a window’s background.  When your application receives a doPreRefresh event, it can draw the background picture only.  The next time your application calls PollSystem, Tools Plus will refresh all its own objects and report a doRefresh event for your application to process.

  When a doPreRefresh event is reported, the window’s “update region” defines the exact area that needs to be refreshed.  Although you can redraw everything in the window, the actual drawing is limited to the parts of the window that are visible and which need refreshing.

Programming Considerations
``````````````````````````
• If your application did not put anything in the window except buttons,
  picture buttons, scroll bars, editing fields, list boxes, pop-up
  menus, and custom controls, it should ignore the doPreRefresh event.

• If your application responds to a doPreRefresh event, it should do so
  in the following manner:


CurrentWindow(Poll.Window);            {Make the affected window the   }
                                       {  current grafPort.            }
BeginUpdate(WindowPointer(Poll.Window));{Drawing will occur only within}
                                        {  the area that needs         }
                                        {  refreshing (includes all    }
                                        {  monitors).                  }
for theScreen:=1 to NumberOfScreens do {Repeat drawing for each monitor}
  begin                                {  in which the window appears. }
    BeginUpdateScreen(theScreen);      {Drawing area reduced to the    }
                                       {  specified screen.            }

    {   …insert your color-dependent drawing code here…   }

    EndUpdateScreen;                   {End the drawing for this       }
                                       {  monitor, and restore the     }
                                       {  window’s visible (drawing)   }
  end;                                 {  region.                      }

 {   …insert your color-independent drawing code here…   }

EndUpdate(WindowPointer(Poll.Window)); {End the update for the window  }
CurrentWindowReset;                    {Reset the current window to be }
                                       {  the same as the active window}
                                       {  (optional command).          }


• BeginUpdate temporarily sets the window’s visRgn (visible region where
  drawing occurs) to the intersection of the visRgn and updateRgn
  (region requiring updating).  This effectively restricts drawing to
  the area that needs updating.  The affected area may include Tools
  Plus objects which are automatically refreshed the next time
  PollSystem is called.

• It is possible that several windows will need to be refreshed
  simultaneously if, for instance, a closing window exposed three
  windows behind it.  PollSystem reports a single doPreRefresh event
  (followed by a doRefresh event) each time it is called in the event
  loop, one event for each window that needs refreshing.

• Unlike ordinary Macintosh applications, a doPreRefresh event is not
  generated when a window is first opened.

• A doPreRefresh event is not generated for desk accessories, the Dialog
  Manager’s dialogs, alerts, or Dynamic Alerts.  These events are
  handled automatically.

• When responding to a doPreRefresh event, your application should limit
  itself to activities that pertain only to refreshing the specified
  window.  Do not create or modify user interface elements, open, close,
  or move windows.

Valid Polling Record Fields
```````````````````````````
Poll.Window

------------------------------------------------------------------------

doGoAway (event)
````````````````
Request to close the active window.

  The request to close the active window is made in response to the user clicking inside the window’s “close” box.  This has the same effect as choosing the File menu’s Close item.

Programming Considerations
``````````````````````````
• A window is closed by using the WindowClose procedure.

• If the window has an active editing field, you may want to validate
  its edited text before allowing the user to close the window.  If this
  is the case, use GetFieldString to obtain a copy of the edited text,
  then your application can check the string for errors.  If an error is
  detected, display an appropriate alert box and ignore the doGoAway
  event.  If no error is detected, call the SaveFieldString procedure to
  save the edited text as the field’s string, then close the required
  window.

• If any changes have been made in the window’s data, your application
  should display an appropriate alert box and ask the user if changes
  should be saved.  The options should be Yes, No, and Cancel, the last
  of which would ignore the doGoAway event.

• The doGoAway event will never occur when the watch cursor is
  displayed, since the close box cannot be clicked.

• A doGoAway event is not generated when the user clicks a desk
  accessory’s close box.  The desk accessory is closed automatically.

• You may want to consider hiding a window (with the WindowDisplay
  routine) instead of closing it in situations where a window is opened
  and closed frequently, such as a floating palette or tool bar.  Hiding
  and showing a window preserves the window’s setting and location, and
  is much faster than opening a window and recreating the user interface
  elements.  However, hiding a window does not release the memory
  consumed by the objects in the window (such as picture buttons, list
  boxes, etc.)

Valid Polling Record Fields
```````````````````````````
Poll.Window
Poll.Modifiers

------------------------------------------------------------------------

doButton (event)
````````````````
Indicator that user has clicked a button.

  The doButton event reports that the user has clicked a button in the active window.  This includes push buttons, check boxes and radio buttons.  The doButton event is also reported if the active window has a default push-button, and the user pressed the Return or Enter key to invoke the default.  If this is the case, the window’s default button will already have been “flashed” as if the user had clicked it.

Programming Considerations
``````````````````````````
• If the user clicked a check box, use SelectButton to reverse the check
  box’s selection (i.e. select or deselect it).

• If the user clicked a radio button, use SelectButton to select the
  radio button, and to deselect the other buttons in the radio button’s
  group.

• This event will never occur when the watch cursor is displayed, since
  buttons cannot be clicked.  The exception is if the WatchCursorButtons
  procedure has been used to allow the watch cursor to click push-
  buttons.

• If your application responds to double-clicks in radio buttons and
  Poll.Button.DoubleClick is true, consider the event to mean “click
  button and OK,” in which case the default button should be flashed and
  the appropriate action taken.

• A doButton event is not generated when the user clicks buttons in a
  dialog box, alert box, or desk accessory.  These events are handled
  automatically.

Valid Polling Record Fields
```````````````````````````
Poll.Window
Poll.Button.Num
Poll.Button.DoubleClick
Poll.Modifiers

------------------------------------------------------------------------

doMenu (event)
``````````````
Indicator that the user selected a pull-down or hierarchical menu item.

  The user selected a pull-down or hierarchical menu by either clicking in the menu bar and selecting an item, or by typing a Command key equivalent for a menu item.

Programming Considerations
``````````````````````````
• The menu’s name in the menu bar is automatically highlighted (white
  letters on black background) when the user makes a menu selection.
  Your application must call MenuHilite(0) to remove the highlighting
  when it is finished with its process.

• If a hierarchical menu item is selected, the name of its ultimate
  parent menu is highlighted in the menu bar (white letters on black
  background).  Your application must call MenuHilite(0) to remove the
  highlighting when it is finished with its process.  If a Command key
  equivalent for a hierarchical menu item is typed, and the hierarchical
  menu is not ultimately attached to a pull-down menu, a doKeyDown or
  doAutoKey event is reported instead (as though the hierarchical menu
  did not exist).

• This event will never occur when a modal window is active, or when the
  watch cursor is displayed since the menu cannot be clicked and Command
  key equivalents are ignored.

• If the active window has an active editing field, PollSystem will
  process the Edit menu’s Undo, Cut, Copy, Paste, and Clear commands
  automatically.  These selections will not generate doMenu events.

• A doMenu event is not generated when the user selects desk accessory
  menus.  These selections are handled automatically.

Valid Polling Record Fields
```````````````````````````
Poll.Menu.Num
Poll.Menu.Item
Poll.Modifiers

------------------------------------------------------------------------

doKeyDown (event)
`````````````````
Indicator that the user pressed down a key.

The user has pressed down a key on the keyboard or numeric pad, and the key cannot be processed internally by Tools Plus.

Programming Considerations
``````````````````````````
• This event is generated only if the key can not be processed
  internally by Tools Plus.

• Command key sequences that are equivalents to menu items generate
  doMenu events.

• If a Command key equivalent for a hierarchical menu item is typed, and
  the hierarchical menu is not ultimately attached to a pull-down menu,
  a doKeyDown or doAutoKey event is reported instead (as though the
  hierarchical menu did not exist).

• The Modifiers field tells your application if the key down event was a
  Command key sequence.  All Command key sequences that are not menu
  equivalents are returned to your application as doKeyDown or doAutoKey
  events.  If your application gets such a Command key sequence, it
  should carry out the appropriate action, or beep the user if the
  Command key sequence is illegal.

• If Return or Enter are typed when the active window has a default
  button, a doButton event is reported for the default button.

• If an active editing field exists on the active window, key strokes
  will affect the field and will not generate events.  This applies even
  if the field’s length is limited, or if Return has been disallowed in
  a field.

• If Tab is typed and the window contains an active editing field, it
  indicates that the user wants to tab to the next field.  Shift-Tab
  indicates tabbing to the previous field.  You may want to validate a
  field’s edited text before allowing the user to tab to the new field.
  If this is the case, use GetFieldString to obtain a copy of the edited
  text, then your application can check the string for errors.  If an
  error is detected, display an appropriate alert box and ignore the
  doKeyDown event.  If no error is detected, call the SaveFieldString
  procedure to save the edited text as the field’s string, then activate
  the new field by using the ActivateField procedure.

• A Return key is reported only if the window does not have a default
  button or active field.

• If Enter is typed, it usually indicates that the user wants to enter
  the screen’s data.  This is the same process that is carried out by
  clicking an OK button.  See “Tab” above, regarding validating and
  saving a field’s edited text.  An Enter key is reported only if the
  window does not have a default button.

• When the watch cursor is displayed, the only doKeyDown event that will
  be reported is a Command-., which indicates that the user is halting a
  lengthy process.  Other doKeyDown events are discarded.

• If the active window has an active editing field, PollSystem
  automatically processes the Command key equivalents for the Edit
  menu’s Undo, Cut, Copy, and Paste commands.  These selections do not
  generate events.

• There are two situations where several keys produce the same key
  character: the Clear and Escape keys, and the F1 through F15 keys.  In
  these cases, use the key code to differentiate the keys.  Constants
  are provided for these key characters and key codes.

• A doKeyDown event is not generated when the user types in a desk
  accessory.  These key strokes are handled automatically.

Valid Polling Record Fields
```````````````````````````
Poll.Window
Poll.Key.Code
Poll.Key.Chr
Poll.Modifiers

------------------------------------------------------------------------

doAutoKey (event)
`````````````````
Indicator that the user held down a key, and it is repeating.

The user has pressed down a key on the keyboard or numeric pad, and the key is repeating.  The key cannot be processed internally by Tools Plus.  In most cases, this event should be treated identically to a doKeyDown event.  Each doAutoKey event will follow a doKeyDown of the same sort, so your application may want to make some repeating Command key sequences illegal.

Programming Considerations
``````````````````````````
• This event is generated only if the key can not be processed
  internally by Tools Plus.

• Command key sequences that are equivalents to menu items generate
  doMenu events.

• If a Command key equivalent for a hierarchical menu item is typed, and
  the hierarchical menu is not ultimately attached to a pull-down menu,
  a doKeyDown or doAutoKey event is reported instead (as though the
  hierarchical menu did not exist).

• The Modifiers field tells your application if the repeating key down
  event was a Command key sequence.  All Command key sequences that are
  not menu equivalents are returned to your application as doKeyDown or
  doAutoKey events.  If your application gets such a Command key
  sequence, it should carry out the appropriate action, or beep the user
  if the Command key sequence is illegal.

• If Return or Enter are typed and held down when the active window has
  a default button, a doButton event is reported for the default button.

• If an active editing field exists on the active window, repeating keys
  will affect the field and will not generate events.  This applies even
  if the field’s length is limited, or if Return has been disallowed in
  a field.

• If Tab is typed and the window contains an active editing field, it
  indicates that the user wants to tab to the next field.  Shift-Tab
  indicates tabbing to the previous field.  You may want to validate a
  field’s edited text before allowing the user to tab to the new field.
    If this is the case, use GetFieldString to obtain a copy of the
  edited text, then your application can check the string for errors.
  If an error is detected, display an appropriate alert box and ignore
  the doKeyDown event.  If no error is detected, call the
  SaveFieldString procedure to save the edited text as the field’s
  string, then activate the new field by using the ActivateField
  procedure.

• A Return key is reported only if the window does not have a default
  button or active field.

• If Enter is typed, it usually indicates that the user wants to enter
  the screen’s data.  This is the same process that is carried out by
  clicking an OK button.  See “Tab” above, regarding validating and
  saving a field’s edited text.  An Enter key is reported only if the
  window does not have a default button.  The repeating Enter key may be
  considered illegal because a doKeyDown event will report the first
  Enter, after which your application should have acted accordingly.  An
  Enter key is reported only if the window does not have a default
  button.

• When the watch cursor is displayed, the only doAutoKey event that will
  be reported is a Command-., which is the user’s request to halt a
  lengthy process.  Other doAutoKey events are discarded.

• If the active window has an active editing field, PollSystem
  automatically processes the Command key equivalents for the Edit
  menu’s Undo, Cut, Copy, and Paste commands.  These selections do not
  generate events.

• There are two situations where several keys produce the same key
  character: the Clear and Escape keys, and the F1 through F15 keys.  In
  these cases, use the key code to differentiate the keys.  Constants
  are provided for these key characters and key codes.

• A doAutoKey event is not generated when the user types in a desk
  accessory.  These key strokes are handled automatically.

Valid Polling Record Fields
```````````````````````````
Poll.Window
Poll.Key.Code
Poll.Key.Chr
Poll.Modifiers

------------------------------------------------------------------------

doKeyUp (event)
```````````````
Indicator that the user released a key.

The user has released a key on the keyboard or numeric pad, and the key cannot be processed internally by Tools Plus.  Normally the Macintosh does not report doKeyUp events nor do applications typically respond to them.  See “Key-Up Events” in the Designing Your Application chapter for details on the SetEventMask procedure.

Programming Considerations
``````````````````````````
• This event is generated only if your application has used the
  SetEventMask procedure to make the Macintosh respond to key-up events,
  and if the active window does not have an active editing field.

• Tools Plus and desk accessories do not require key-up events, and
  therefore ignore them.

• There are two situations where several keys produce the same key
  character: the Clear and Escape keys, and the F1 through F15 keys.  In
  these cases, use the key code to differentiate the keys.  Constants
  are provided for these key characters and key codes.

• When the watch cursor is displayed, all doKeyUp events are discarded
  and are not generated.

Valid Polling Record Fields
```````````````````````````
Poll.Window
Poll.Key.Code
Poll.Key.Chr
Poll.Modifiers

------------------------------------------------------------------------

doClickField (event)
````````````````````
Indicator that the user clicked in an inactive editing field.

When the user clicks in an inactive editing field in the active window, it indicates that the user has finished working with the currently active field and wants to start working with the one that was clicked.  Tools Plus automatically supports the full range of Macintosh user interface options for editing fields, including (but not limited to):
  • clicking in the field, thereby placing an insertion point
  • dragging across characters to create a selection
  • double-clicking a word to select it

Programming Considerations
``````````````````````````
• The ClickInField procedure is used to process a user’s click in an
  inactive editing field.  It could be in the same window that the user
  is working in, or it could be in a tool bar or floating palette

• If an editing field is active when you receive a doClickField event,
  you may want to validate its edited text before allowing the user to
  click to the new field.  If this is the case, use GetFieldString to
  obtain a copy of the edited text, then your application can check the
  string for errors.  If an error is detected, display an appropriate
  alert box and ignore the doClickField event.  If no error is detected,
  call the SaveFieldString procedure to save the edited text as the
  field’s string, then call the ClickInField procedure to process the
  user’s click in the new field.

• Between the time that the doClickField event is reported and the
  ClickInField procedure is used as a response, observe the following
  rules:
      • do not call PollSystem
      • do not open or close any windows, including alerts and dialogs
      • do not hide or show any windows
      • do not activate any windows.
  If these rules are not observed, ClickInField will do nothing and the
  user’s click is ignored.

• An event will not occur if the user clicks in an editing field that is
  already active.

• This event will never occur when the watch cursor is displayed, since
  editing fields cannot be clicked.

• A doClickField event is not generated when the user clicks in a desk
  accessory’s editing fields.  The process is handled automatically.

Valid Polling Record Fields
```````````````````````````
Poll.Window
Poll.Field
Poll.Modifiers

------------------------------------------------------------------------

doScrollBar (event)
```````````````````
Indicator that user clicked in a scroll bar.

The doScrollBar event reports that the user has clicked somewhere in a scroll bar.  The scroll bar has 5 parts: up button, down button, “page up” region, “page down” region, and the thumb.  In all cases, your application should respond to the scroll bar event by scrolling the window’s contents (or portion thereof) and drawing any parts that have been newly revealed due to scrolling.

Programming Considerations
``````````````````````````
• If the scroll bar’s thumb was moved, your application can obtain the
  current value of the scroll bar by calling GetScrollBarVal.  By using
  this value, your application can determine how much to scroll.

• If the scroll bar’s up button, down button, “page up” region, or “page
  down” region was clicked, your application must scroll the window by
  the correct amount, then change the scroll bar’s value by using
  SetScrollBarVal.

• If the up arrow or “page up” region is clicked, subtract the correct
  amount from the current value.  If the down arrow or “page down”
  region is clicked, add the correct amount to the current value.

• If the user holds the mouse button down in the up arrow, “page up”
  region, down arrow, or “page down” region, PollSystem returns a single
  doScrollBar event each time PollSystem is called.  Your application
  doesn’t have to be aware of this, but it is nice to know that scroll
  bar events will not pile up in the queue.

• If the user moves the scroll bar’s thumb and returns it to its
  original place during the same drag, an event is not generated.

• This event will never occur when the watch cursor is displayed, since
  scroll bars cannot be clicked.

• Scroll bars that are part of a list box are handled automatically.

• A doScrollBar event is not generated when the user clicks scroll bars
  in a dialog box or desk accessory.  These events are handled
  automatically.

Valid Polling Record Fields
```````````````````````````
Poll.Window
Poll.ScrollBar.Num
Poll.ScrollBar.Part

------------------------------------------------------------------------